Annolid Bot Background Services Setup

This tutorial helps you configure optional background services safely:

• Email polling/sending

• WhatsApp bridge/webhook channel

• Zulip channel

• Google Calendar tool

If optional packages are missing, Annolid now skips those features and keeps the app running.

1. Install optional extras you actually need

# Recommended bundle for most Annolid Bot users
pip install "annolid[annolid_bot]"

For WhatsApp QR bridge, also install Chromium runtime:

python -m playwright install chromium

2. Minimal safe config (~/.annolid/agent/config.json)

Start with disabled services, then enable one at a time:

{
  "tools": {
    "email": {
      "enabled": false
    },
    "whatsapp": {
      "enabled": false,
      "autoStart": false
    },
    "zulip": {
      "enabled": false
    },
    "calendar": {
      "enabled": false,
      "provider": "google"
    }
  }
}

3. Enable WhatsApp (optional)

See full guide: docs/source/agent_whatsapp_tutorial.md

• Set tools.whatsapp.enabled=true

• Set tools.whatsapp.autoStart=true

• Keep bridgeMode="python" for local QR bridge mode

If websockets/Playwright deps are missing, Annolid logs a warning and continues without WhatsApp startup.

4. Enable Zulip (optional)

See full guide: docs/source/agent_zulip_tutorial.md

• Set tools.zulip.enabled=true

• Provide:

  • tools.zulip.server_url

  • tools.zulip.user

  • tools.zulip.api_key

• Optionally set stream, topic, and allow_from

5. Enable Google Calendar (optional)

See full guide: docs/source/agent_google_calendar_tutorial.md

• Set tools.calendar.enabled=true

• Install annolid[annolid_bot]

• Provide OAuth credentials file

If Google auth/client deps are missing, Annolid logs a warning and skips registering the calendar tool.

6. Common errors and quick fixes

• No module named 'websockets'

  • Run: pip install "annolid[annolid_bot]"

• No module named 'google.auth'

  • Run: pip install "annolid[annolid_bot]"

• Zulip channel enabled but no traffic

  • Verify server_url, user, api_key

  • Verify allow_from is not filtering expected senders

• Background services should not auto-start

  • Set:

    • tools.whatsapp.autoStart=false

    • tools.email.enabled=false

    • tools.zulip.enabled=false

    • tools.calendar.enabled=false

7. Verify from your environment

python -c "import importlib.util as u; print('websockets', u.find_spec('websockets') is not None)"
python -c "import importlib.util as u; print('google.auth', u.find_spec('google.auth') is not None)"

If both print False, keep those services disabled in config until you install matching extras.